% !TEX encoding = UTF-8 Unicode
% !TEX TS-program = XeLaTeX
% !TEX root = ParliamentUserGuide.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Deploying and Using \acl{pmnt}}
\label{chapter-deploying-and-using}

There are several ways to use \ac{pmnt}.  By far the most common is as a server application that exposes a \ac{sparql} endpoint.  The binary distribution directly supports this usage, running \ac{pmnt} within the included Jetty servlet engine.  See Section~\ref{section-std-server-deploy} for complete instructions.

\ac{pmnt} can also be used with other servlet engines such as Tomcat and Glassfish (see Section~\ref{section-parliament-with-jena-and-tomcat}) or as an in-process library (Section~\ref{section-parliament-in-process}).

Pre-built binaries for common platforms are available on the \ac{pmnt} Web site\urlcite{http://parliament.semwebcentral.org/}.  You can also build \ac{pmnt} yourself (see Chapter~\ref{chapter-building-parliament}).

This chapter starts with instructions for installing a \ac{pmnt} server (Section~\ref{section-std-server-deploy}), followed by a discussion of the \ac{pmnt} configuration file (Section~\ref{section-configuring-pmnt}).  Then comes a detailed discussion of each of the less common deployment scenarios.  The chapter concludes with discussions of \ac{pmnt} utilities and troubleshooting (Sections~\ref{section-parliamentadmin-utility} and~\ref{section-troubleshooting}).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Deploying a \ac{pmnt} Server}
\label{section-std-server-deploy}

A \ac{pmnt} distribution is a compressed archive containing a ready-to-run \ac{pmnt} Server, with the following naming convention:
\begin{quote}
	\texttt{Parliament-v\textbf{\textit{X.Y.Z}}-\textbf{\textit{toolset}}.zip}
\end{quote}
Here \texttt{\textbf{\textit{X.Y.Z}}} is the \ac{pmnt} version number and \texttt{\textbf{\textit{toolset}}} indicates the platform on which the distribution runs, as shown in Table~\ref{tbl:ToolsetPlatformCorrespondence}.
\begin{table}[htbp]
	\centering
	\begin{tabular}{ll}
		\toprule
		\emph{Toolset}		& \emph{Corresponding Platform}\\
		\headingrule
		\path|clang|		& Universal binaries for Mac OS X\\
		\path|gcc-centos|	& 64-bit CentOS Linux\\
		\path|gcc-ubuntu|	& 64-bit Ubuntu Linux\\
		\path|msvc-64|		& 64-bit Windows\\
		\path|msvc-32|		& 32-bit Windows\\
		\bottomrule
	\end{tabular}
	\caption{Toolset-to-Platform Correspondence}
	\label{tbl:ToolsetPlatformCorrespondence}
\end{table}
If you are building \ac{pmnt} yourself according to the instructions in Chapter~\ref{chapter-building-parliament}, then these archives appear in the \path|target/distro| directory at the end of the build process.

As shown in Table~\ref{tbl:ToolsetPlatformCorrespondence}, on Windows there is a choice between 32-bit and 64-bit builds.  Whenever possible, use the 64-bit version, because 32-bit \ac{pmnt} is limited to 5 to 10 million statements.

\subsection{Installing for the First Time}
\label{section-std-server-init-deploy}

Once you have downloaded a distribution, these steps will yield a functioning \ac{kb}:
\begin{enumerate}
	\item Extract the archive to the location of your choice.  On UNIX-like systems, \path|/usr/opt/ParliamentKB| or \path|/usr/local/ParliamentKB| is a likely choice.  On Windows, \path|C:\Program Files\ParliamentKB| is customary.  The instructions that follow refer to this directory as simply \path|ParliamentKB|.

	\item On Windows, install the C and C++ run-time libraries.  You can find installers for these in the following directory:
	\begin{quote}
		\path|ParliamentKB/RedistributablePackages|
	\end{quote}

	\item From the \path|ParliamentKB| directory, invoke the startup script to start the \ac{pmnt} server.  This is called \path|StartParliament.bat| on Windows and \path|StartParliament.sh| on other platforms\footnote{On all platforms, these scripts locate your Java installation by simply invoking the command \path|java| and relying on the operating system's native facilities for locating the \ac{jvm} executable.  See Section~\ref{section-troubleshooting} for more information.}.
\end{enumerate}

The procedure above uses \acp{pmnt} standard startup script, which directly starts the server.  However, in many cases it is preferable to run \ac{pmnt} as a Windows service or as a UNIX daemon.

\subsubsection{Installing as a Windows Service}

The script \path|InstallParliamentService.bat| installs \ac{pmnt} as a Windows service.  This script uses the \verb|JAVA_HOME| environment variable to locate your Java installation\footnote{See Section~\ref{section-troubleshooting} for information about choosing among multiple Java installations.}.  After running this script, use the Services management console to start and stop \ac{pmnt} and to run \ac{pmnt} automatically upon system startup.

Usually, \ac{pmnt} cannot be installed as a Windows service if it resides on a mapped network drive.  This is because the mapping is an artifact of your user login, and services run outside that context.

If you change any of the parameters in \path|InstallParliamentService.bat| (see Section~\ref{section-configuring-pmnt}), you will need to re-run it in order to have those changes reflected in the installed service definition.

Uninstall the service with \path|UninstallParliamentService.bat|.

\subsubsection{Installing as a Linux/UNIX Daemon}

For variants of Linux that support System D, such as CentOS and Ubuntu, Parliament includes the \path|InstallService.sh| script, which will install \ac{pmnt} as a System D service.  (You will likely need elevated rights to run this script, such as those provided by \path|sudo|.)  Thereafter, \ac{pmnt} can be controlled via the \path|systemctl| command, for instance:
\begin{quote}
	\path|systemctl start parliament|
\end{quote}
or
\begin{quote}
	\path|systemctl stop parliament|
\end{quote}

To uninstall \ac{pmnt} as a System D service, first run the following commands (again, you will likely need elevated rights):
\begin{quote}
	\path|systemctl stop parliament|\\
	\path|systemctl disable parliament|
\end{quote}

Then delete this file:
\begin{quote}
	\path|/etc/systemd/system/parliament.service|
\end{quote}

For other Linux variants (and for UNIX), the \path|StartParliamentDaemon.sh| script will start \ac{pmnt} as a daemon.  The exact method for wiring this into the operating system's infrastructure for starting and stopping daemon processes varies from platform to platform.



\subsection{Upgrading an Existing Installation}
\label{section-std-server-upgrade}

When upgrading an existing \ac{pmnt} installation to a newer version, the procedures of Section~\ref{section-std-server-init-deploy} are generally not sufficient because they ignore the migration of the data.  The \ac{pmnt} development team strives to maintain compatibility of file formats whenever possible.  In such cases, all that is required is to move the \path|kb-data| subdirectory of your \ac{pmnt} installation into the new \ac{pmnt} installation.  (Of course, if you have customized \acp{pmnt} configuration, you will also need to make those changes in the new installation as well.)

However, from time to time \acp{pmnt} file formats do change, and in such cases a different migration procedure is required.  Following this procedure even in those cases where it is not required has some benefits as well, since it frees up any unused space in the \ac{pmnt} files.  This is the way to perform such a migration:

\begin{enumerate}
	\item\label{upgrade-procedure-first-step}\textbf{\emph{Before upgrading,}} point your browser at your \ac{pmnt} server.  The \ac{url} for this is \nolinkurl{http://<host>:<port>/parliament/}.  By default this will be \nolinkurl{http://localhost:8089/parliament/}.

	\item Click on the ``Export'' link.

	\item\label{item-export-download}Click on the ``Export Repository'' button.  This will start a download whose file name looks like this:
\begin{quote}\path|parliament-export-localhost-<date>-<time>.zip|\end{quote}

	\item When the download finishes, shut down \ac{pmnt}.  Rename the \ac{pmnt} installation directory if you want your upgraded installation to reside in the same place.

	\item Unzip the new version of \ac{pmnt} to your desired location.

	\item Customize the new installation's settings as required.  For more information, see Section~\ref{section-configuring-pmnt}.

	\item Start up the new \ac{pmnt} installation.

	\item Point your browser at the new \ac{pmnt} server.  The \ac{url} is the same as the one in Step~\ref{upgrade-procedure-first-step} above.

	\item Click on the ``Insert Data'' link.

	\item In the ``Import Repository'' section, press the ``Choose File'' button and select the file you downloaded in Step~\ref{item-export-download} above.  Then press the ``Import Repository'' button.
\end{enumerate}

Once you see the ``Insert operation successful'' message, your upgraded \ac{pmnt} server is ready for business.

\subsection{Usage}
\label{section-std-server-usage}

\emph{Important note:}  When you shut down \ac{pmnt}, it is important to shut it down gracefully.  Otherwise, the \ac{pmnt} files may not be flushed to disk before they are closed, and they may be badly corrupted.  If you run \ac{pmnt} as a Windows service or UNIX Daemon (see Section~\ref{section-std-server-init-deploy}), this is generally not a problem, because the operating system sends a shut-down message at the appropriate times.  If, however, you run \ac{pmnt} explicitly via \path|StartParliament.sh| (or \path|StartParliament.bat| on Windows), you will need to shut it down yourself by typing the command ``exit'' followed by «return» or «enter».

To use the \ac{pmnt} server, you will need the the connection \acp{url} listed in Table~\ref{table-pmnt-connect-urls}.  (See Section~\ref{section-configuring-pmnt} to configure your server to run on a host name and port other than ``localhost'' and ``8089''.)
\begin{table}[htbp]
	\centering\small
	\begin{tabular}{ll}
		\acs*{http} interface: & \nolinkurl{http://localhost:8089/parliament}\\
		\ac{sparql} endpoint: & \nolinkurl{http://localhost:8089/parliament/sparql}\\
		Bulk loader: & \nolinkurl{http://localhost:8089/parliament/bulk}\\
	\end{tabular}
	\caption{\acs*{pmnt} Server Connection \acsp*{url}}
	\label{table-pmnt-connect-urls}
\end{table}
You can use the \ac{pmnt} server interactively by pointing your web browser at the \ac{http} interface \ac{url} from Table~\ref{table-pmnt-connect-urls}.  This simple and (hopefully) self-explanatory web interface is useful for initial data loading, experimenting with queries, exploring a collection of data, troubleshooting, and similar tasks.

In order to issue queries programmatically, you will need to write some code to send \ac{sparql}-compliant \ac{http} requests.  One library that can send such requests on your behalf is Jena itself.  Figure~\ref{figure-sparql-select-query-with-jena} shows sample code for issuing a \ac{sparql} select query.
\begin{figure}[htbp]
	\footnotesize
	\begin{verbatim}
import com.hp.hpl.jena.query.QueryExecution;
import com.hp.hpl.jena.query.QueryExecutionFactory;
import com.hp.hpl.jena.query.ResultSet;

void issueSelectQuery(String sparqlSelectQuery)
{
  QueryExecution exec = QueryExecutionFactory.sparqlService(
    "http://localhost:8089/parliament/sparql",
    sparqlSelectQuery);
  for (ResultSet rs = exec.execSelect(); rs.hasNext(); rs.next())
  {
    // Do something useful with the result set here
  }
}
	\end{verbatim}
	\caption{Issuing a \acs*{sparql} select query with Jena}
	\label{figure-sparql-select-query-with-jena}
\end{figure}
Note that this code uses the \ac{sparql} endpoint \ac{url} from Table~\ref{table-pmnt-connect-urls}.

\ac{pmnt} also provides a Java library to help programmers interact with the \ac{pmnt} server, which can be found here:
\begin{quote}
	\path|ParliamentKB/lib/JosekiParliamentClient.jar|
\end{quote}
This library leverages the Jena functionality shown above, but exposes a few extra features of the \ac{pmnt} server that are not accessible within the bounds of \ac{sparql}.  To use this approach, first add the above jar file to your class path.  Then create a \verb|RemoteModel| object as shown in Figure~\ref{figure-using-remote-jena-model}.  This object allows you to access and manipulate the \ac{pmnt} repository identified by the \acp{url} passed to the constructor, which are again taken from Table~\ref{table-pmnt-connect-urls}.
\begin{figure}[htbp]
	\footnotesize
	\centering
	\begin{verbatim}
import com.bbn.parliament.jena.joseki.client.RemoteModel;

void useRemoteParliamentModel()
{
  // Create model:
  RemoteModel rmParliament = new RemoteModel(
    "http://localhost:8089/parliament/sparql",
    "http://localhost:8089/parliament/bulk");

  // Insert contents of another Jena Model:
  rmParliament.insertStatements(myPopulatedJenaModel);

  // Perform SPARQL SELECT query:
  ResultSet results = rmParliament.selectQuery(myQueryString);

  // Add statements using SPARQL-UPDATE:
  rmParliament.updateQuery(mySparqlUpdateQueryString);
}
	\end{verbatim}
	\caption{Using \ac{pmnt} Via a Remote Jena Model}
	\label{figure-using-remote-jena-model}
\end{figure}
Note that the query strings passed to the remote model in Figure~\ref{figure-using-remote-jena-model} follow standard \ac{sparql} and \ac{sparql}-UPDATE formats, including support for named graphs.  Also note that the \verb|RemoteModel| class exposes the bulk loading feature of the \ac{pmnt} server, allowing the loading of large bodies of \ac{rdf} efficiently.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Configuring \ac{pmnt}}
\label{section-configuring-pmnt}

\ac{pmnt} has a few configuration files, discussed in the sections below.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{\acp{pmnt} Startup Scripts}

You can change the host name (or IP address) and port of the \ac{sparql} endpoint by setting \verb|JETTY_HOST| and \verb|JETTY_PORT| in the startup script.  These default to \verb|localhost| and 8089, respectively.  To make \ac{pmnt} addressable on any of a host's network interfaces, change \verb|JETTY_HOST| to ``0.0.0.0''.

You can control the amount of memory set aside for the Java virtual machine's heap by setting \verb|MIN_MEM| and \verb|MAX_MEM| in the same location.  While it is important to allow the \ac{jvm} sufficient memory, it is also important to realize that a significant portion of \ac{pmnt} is native code, and therefore does not use the Java heap.  Java programmers are often inclined to set \verb|MAX_MEM| close to the total memory of the machine, but this will starve \acp{pmnt} native code of the memory it needs to achieve good performance.  The default heap size ranges from 128 MB to 512 MB, which is reasonable for machines with 4 to 8 GB of total memory.

Note that if you are running the server as a Windows service, you must change these parameters in the install script, and you will have to re-run the install script to make your changes effective.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{\acp{pmnt} Main Configuration File}

\acp{pmnt} main configuration file contains settings pertaining to storage, query, and inference.  It is typically called \path|ParliamentKbConfig.txt|, and \ac{pmnt} finds it like so:

\begin{enumerate}
	\item If the environment variable \verb|PARLIAMENT_KB_CONFIG_PATH| is set, its value is assumed to be the configuration file's absolute path.  Note that using this option, you can rename the file to anything you wish.

	\item \emph{On Windows only:}  If this environment variable is not set, then \ac{pmnt} looks for a file named \path|ParliamentKbConfig.txt| in the same directory as the \ac{pmnt} \ac{dll}.

	\item Otherwise, \ac{pmnt} looks for a file named \path|ParliamentKbConfig.txt| in the current working directory of the server process.
\end{enumerate}

The configuration file is a plain text file containing name-value pairs.  The names are case-insensitive.  Blank lines and comment lines (preceded by a `\#') are ignored.  Many of the settings are Boolean values, in which case the value is case-insensitive and may be ``true'', ``t'', ``yes'', ``y'', ``on'', or ``1'' (for true), or ``false'', ``f'', ``no'', ``n'', ``off'', or ``0'' (for false).

The recognized settings are as follows:
\begin{description}
	\item[kbDirectoryPath] The path of the \ac{pmnt} knowledge base files.  If they do not yet exist, they will be created here.  \emph{Default: \path|kb-data|}

	\item[stmtFileName] The name of the memory-mapped file containing records of statements. \emph{Default: \path|statements.mem|}

	\item[rsrcFileName] The name of the memory-mapped file that contains resource records. \emph{Default: \path|resources.mem|}

	\item[uriTableFileName] The name of the memory-mapped file containing resource strings (URIs and literals). \emph{Default: \path|uris.mem|}

	\item[uriToIntFileName] The name of the file containing the mapping from numeric resource identifiers to resource strings.  This file is managed by Berkeley DB. \emph{Default: \path|u2i.db|}

	\item[stmtToIdFileName] This obsolete setting is now ignored.  It indicated the name of a file that mapped tuples of numeric resource identifiers to numeric statement identifiers.  This file was omitted by default, and was included only if the setting ``keepDupStmtIdx'' was turned on.  The default value was \path|stmt2id.db|.  If your configuration had ``keepDupStmtIdx'' turned off, then you can safely delete these two settings from your configuration file.  If it was turned on, then delete the file named by this setting and then delete these two settings from your configuration file.

	\item[keepDupStmtIdx] This obsolete setting is now ignored.  If set to ``yes'', \ac{pmnt} would maintain an extra file (named by the ``stmtToIdFileName'' option).  It was intended to be a performance optimization, but it rarely helped.  It defaulted to ``no''.  If you had this turned off then you can simply delete this and the ``stmtToIdFileName'' options from your configuration.  If it was turned on, then delete the file named by the ``stmtToIdFileName'' option and then delete these two settings from your configuration file.

	\item[readOnly] When set to ``yes'', prevents \ac{pmnt} from changing the underlying storage files in any way. \emph{Default: ``no''}

	\item[fileSyncTimerDelay] \ac{pmnt} periodically flushes its underlying data files to disk to decrease the chances of a file corruption and to limit the amount of time required to shut down \ac{pmnt} gracefully.  This parameter is the time interval in milliseconds between flushes.  Set it to zero to disable flushing the files to disk.  This setting applies only to \ac{pmnt} deployed as a server using Jena, Joseki, and Jetty.  Any other deployment will ignore this setting. \emph{Default: ``15000''}

	\item[initialRsrcCapacity] The number of resources \ac{pmnt} should allocate space for when creating a new \ac{kb}. \emph{Default: ``300000''}

	\item[avgRsrcLen] The average resource length (in characters) that \ac{pmnt} should anticipate when allocating space in a new \ac{kb}. \emph{Default: ``100''}

	\item[rsrcGrowthIncrement] The number of resources by which \ac{pmnt} increases the resource table size when it runs out of space in the file.  If this is less than one, then linear growth of the resource table is disabled, in which case rsrcGrowthFactor must be larger than one (see below). \emph{Default: ``600000''}

	\item[rsrcGrowthFactor] The factor by which \ac{pmnt} increases the size of the resource table when it runs out of space in the file.  If this is less than or equal to one, then geometric growth of the resource table is disabled, in which case rsrcGrowthIncrement must be at least one (see above).  Note that this is a decimal number that should be formatted according to your locale, e.g., ``1.1`` in the US or ``1,1'' in Europe. \emph{Default: ``0''}

	\item[initialStmtCapacity] The number of statements \ac{pmnt} should allocate space for when creating a new \ac{kb}. \emph{Default: ``500000''}

	\item[stmtGrowthIncrement] The number of statements \ac{pmnt} adds to the statement table size when it runs out of space in the file.  If this is less than one, then linear growth of the statement table is disabled, in which case stmtGrowthFactor must be larger than one (see below). \emph{Default: ``1000000''}

	\item[stmtGrowthFactor] The factor by which \ac{pmnt} increases the size of the statement table when it runs out of space in the file.  If this is less than or equal to one, then geometric growth of the statement table is disabled, in which case stmtGrowthIncrement must be at least one (see above).  Note that this is a decimal number that should be formatted according to your locale, e.g., ``1.1`` in the US or ``1,1'' in Europe. \emph{Default: ``0''}

	\item[bdbCacheSize] The amount of memory to be devoted to the Berkeley DB cache.  The portion before the comma is the total cache size (with a k for kilobytes, m for megabytes, g for gigabytes).  The portion after the comma specifies how many segments the memory should be broken across, for compatibility with systems that limit the size of single memory allocations.  On systems with 4 GB or more of memory, setting this to ``256m,1'' generally seems to be optimal. \emph{Default: ``32m,1''}

	\item[normalizeTypedStringLiterals] Instructs \ac{pmnt} to convert typed string literals to plain literals, both upon insert and at query time, as mandated in \ac{rdf} 1.1.  In \ac{pmnt} versions before the implementation of this option (versions~2.7.9 and prior), the behavior was as if the option were set to ``no''.  Therefore, if you are migrating a \ac{pmnt} installation originally created with one of these older versions to a newer version, you must do one of two things:
	\begin{enumerate}
		\item Either before or after the upgrade, create an export of the entire triple store.  To do this, use the ``Export Repository'' option on the Export page of \acp{pmnt} Web-based administrative interface.  Then shut down \ac{pmnt} and delete its \path|kb-data| (or \path|data|) directory.  This is the location identified by the \texttt{kbDirectoryPath} setting in the configuration file.  Then, after upgrading, import the backup using the ``Import Repository'' option on the Insert Data page of the administrative interface.

		\item Set this option to ``no''.
	\end{enumerate}
	The first option is highly recommended.  It requires some effort, but will bring your triple store into compliance with \ac{rdf} 1.1 and deliver slightly better performance to boot.  \emph{Default: ``yes''}

	\item[TimeoutDuration] Sets the query execution timeout. \emph{Default: ``5''}

	\item[TimeoutUnit] Sets the units of the query execution timeout.  Valid values are ``nanoseconds'', ``microseconds'', ``milliseconds'', ``seconds'', ``minutes'', ``hours'', and ``days''. \emph{Default: ``minutes''}

	\item[runAllRulesAtStartup] Causes \ac{pmnt} to evaluate each of the enabled rules at startup against the existing statements in the \ac{kb} to see if any new statements should be materialized.  Generally, this is unnecessary, because the rules are always evaluated against each statement as it is asserted.  However, if some of the rules were initially disabled when statements were being asserted, and are then enabled, it may be necessary to turn this on for one startup of \ac{pmnt} to ensure that the state of the \ac{kb} is in sync with the rule settings.  Alternately, in such a case this setting may be left off and the ParliamentAdmin tool may be run against the \ac{kb} with the ``guaranteeEntailments'' option.  Note that when this setting is turned on, \ac{kb} the startup time may be lengthy. \emph{Default: ``no''}

	\item[enableSWRLRuleEngine] Enables an additional rule engine that implements the \ac{swrl} rule language. \emph{Default: ``no''}

	\item[SubclassRule] Enables the following inference rules:
\[A \subset B \land B \subset C \Rightarrow A \subset C\]
\[X \in A \land A \subset B \Rightarrow X \in B\]
\[X \in \text{rdfs:Class} \Rightarrow X \subset X\]
\[X \in \text{owl:Class} \Rightarrow X \subset X\]
where $\subset$ means ``sub-class of'' and $\in$ means ``of type''. \emph{Default: ``on''}

	\item[inferRdfsClass] When both this setting and ``SubclassRule'' are turned on, this enables the following inference rule:
\[A \subset B \Rightarrow A \in \text{rdfs:Class} \land B \in \text{rdfs:Class}\]
where $\subset$ means ``sub-class of'' and $\in$ means ``of type''. \emph{Default: ``off''}

	\item[inferOwlClass] When both this setting and ``SubclassRule'' are turned on, this enables the following inference rule:
\[A \subset B \Rightarrow A \in \text{owl:Class} \land B \in \text{owl:Class}\]
where $\subset$ means ``sub-class of'' and $\in$ means ``of type''. \emph{Default: ``off''}

	\item[inferRdfsResource] When both this and the ``SubclassRule'' settings are turned on, the following inference rule is enabled:
\[A \subset B \Rightarrow A \subset \text{rdfs:Resource} \land B \subset \text{rdfs:Resource}\]
where $\subset$ means ``sub-class of''. \emph{Default: ``off''}

	\item[inferOwlThing] When both this setting and ``SubclassRule'' are turned on, this enables the following inference rule:
\[A \subset B \Rightarrow A \subset \text{owl:Thing} \land B \subset \text{owl:Thing}\]
where $\subset$ means ``sub-class of''. \emph{Default: ``off''}

	\item[SubpropertyRule] Enables the following inference rules:
\[P \sqsubset Q \land Q \sqsubset R \Rightarrow P \sqsubset R\]
\[P \sqsubset Q \land P(X, Y) \Rightarrow Q(X, Y)\]
where $\sqsubset$ means ``sub-property of''. \emph{Default: ``on''}

	\item[DomainRule] Enables the following inference rule:
\[\text{rdfs:domain}(P,C) \land P(X, Y) \Rightarrow X \in C\]
\emph{Default: ``on''}

	\item[RangeRule] Enables the following inference rule:
\[\text{rdfs:range}(P,C) \land P(X, Y) \Rightarrow Y \in C\]
\emph{Default: ``on''}

	\item[EquivalentClassRule] Enables the following inference rule:
\[\text{owl:equivalentClass}(A,B) \Rightarrow A \subset B \land B \subset A\]
where $\subset$ means ``sub-class of''. \emph{Default: ``on''}

	\item[EquivalentPropRule] Enables the following inference rule:
\[\text{owl:equivalentProperty}(P,Q) \Rightarrow P \sqsubset Q \land Q \sqsubset P\]
where $\sqsubset$ means ``sub-property of''. \emph{Default: ``on''}

	\item[InverseOfRule] Enables the following inference rule:
\[\text{owl:inverseOf}(P, Q) \land P(X, Y) \Rightarrow Q(Y, X)\]
\emph{Default: ``on''}

	\item[SymmetricPropRule] Enables the following inference rule:
\[P \in \text{owl:SymmetricProperty} \land P(X, Y) \Rightarrow P(Y, X)\]
\emph{Default: ``on''}

	\item[FunctionalPropRule] Enables the following inference rule:
\[P \in \text{owl:FP} \land P(Z, X) \land P(Z, Y) \Rightarrow \text{owl:sameAs}(X, Y)\]
where ``FP'' stands for ``FunctionalProperty''. \emph{Default: ``on''}

	\item[InvFunctionalPropRule] Enables the following inference rule:
\[P \in \text{owl:IFP} \land P(X, Z) \land P(Y, Z) \Rightarrow \text{owl:sameAs}(X, Y)\]
where ``IFP'' stands for ``InverseFunctionalProperty''. \emph{Default: ``on''}

	\item[TransitivePropRule] Enables the following inference rule:
\[P \in \text{owl:TransitiveProperty} \land P(X, Y) \land P(Y, Z) \Rightarrow P(X, Z)\]
\emph{Default: ``on''}
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{\acp{pmnt} Logging Configuration}

These files configure logging for \acp{pmnt} Java code:
\begin{quote}
	\path|ParliamentKB/conf/log4j.interactive.properties|\\
	\path|ParliamentKB/conf/log4j.daemon.properties|
\end{quote}
They are standard Log4J configuration files.  The first applies when running \ac{pmnt} from the command line, and the second is used when running as a daemon or service.

The file \path|ParliamentLogConfig.txt| controls native code logging.  Its format is similar to \path|ParliamentKbConfig.txt|, and it is located in a similar way, using file name \path|ParliamentLogConfig.txt| and the environment variable \verb|PARLIAMENT_LOG_CONFIG_PATH|.  The recognized settings are:
\begin{description}
	\item[logToConsole] Indicates whether to log to the console. \emph{Default: ``yes''}

	\item[logConsoleAsynchronous] Indicates whether to log asynchronously to the console. \emph{Default: ``no''}

	\item[logConsoleAutoFlush] Indicates whether console log entries should be flushed after each log operation. \emph{Default: ``yes''}

	\item[logToFile] Indicates whether to log to a file. \emph{Default: ``yes''}

	\item[logFilePath] The path of the log file.  May include the following placeholders to add contextual information to the file name:
	\begin{description}[noitemsep]
		\item[\texttt{\%N}]Cardinal number of the log file.  A number between the \% and the N will left-pad with zeros to that many places.
		\item[\texttt{\%Y}]Year
		\item[\texttt{\%m}]Month
		\item[\texttt{\%d}]Day
		\item[\texttt{\%H}]Hours
		\item[\texttt{\%M}]Minutes
		\item[\texttt{\%S}]Seconds
	\end{description}
	\emph{Default:} \texttt{log/ParliamentNative\%3N\_\%Y-\%m-\%d\_\%H-\%M-\%S.log}

	\item[logFileAsynchronous] Indicates whether to log asynchronously to the file. \emph{Default: ``no''}

	\item[logFileAutoFlush] Indicates whether file log entries should be flushed after each log operation. \emph{Default: ``yes''}

	\item[logFileRotationSize] The maximum approximate size (in bytes) of the log file.  When this value is exceeded, the log file will be rotated. \emph{Default: 10 MB}

	\item[logFileMaxAccumSize] The maximum accumulated size of rotated log files.  When this value is exceeded, the oldest log file is deleted. \emph{Default: 150 MB}

	\item[logFileMinFreeSpace] The minimum amount of free space on the volume where log files are stored.  When the free space dips below this value, old log files will be deleted so as to free up enough space. \emph{Default: 100 MB}

	\item[logFileRotationTimePoint] The time of day at which the log file should be rotated regardless of its size.  Must be in the format ``HH:MM:SS''. \emph{Default: 2:00 AM}

	\item[logLevel] The global logging level.  Must be one of TRACE, DEBUG, INFO, WARN, and ERROR. \emph{Default: ``INFO''}

	\item[logChannelLevel] Overrides the global logging level for a single channel.  (Generally a channel is equivalent to a class in the source code.)  The value of this setting takes the form \begin{quote}\emph{«channel-name» = «log-level»}\end{quote} where \emph{«log-level»} takes one of the values listed for the global logging level above.  This option may be repeated to override the level for multiple channels. \emph{Default: None}
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{\acp{pmnt} Servlet Container Configuration File}

The file \path|ParliamentKB/conf/jetty.xml| configures the Jetty servlet container.  Generally, there is no need to modify this file.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\ac{pmnt}-Specific Features}
\label{section-parliament-specific-features}

\ac{pmnt} has a number of features beyond those implied by the \ac{rdf}, \ac{owl}, and \ac{sparql} standards, detailed in the sub-sections below.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Reserved Predicates}
\label{section-reserved-predicates}

The \verb|par:directType| and \verb|par:directSubClassOf| predicates are treated specially by \ac{pmnt}.  They are reserved in the sense that they may not be used as the subject, predicate, or object of any  statements inserted in \ac{pmnt}.  However, when used in queries they have special meanings.

In queries, \verb|par:directType| is interpreted like \verb|rdf:type| except that inferred statements are ignored.  Similarly, \verb|par:directSubClassOf| is the same as \verb|rdf:subClassOf| except that it ignores inferred statements.  These predicates provide high-performance shortcuts for queries that are looking for a ``most-derived type.''  For instance, to find the most-derived type of a resource \verb|?x|, we can use the following query:

{\small\begin{verbatim}
prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
select distinct ?x ?type where {
   ?x a ?type .
   filter not exists {
      ?x a ?type2 .
      ?type2 rdfs:subClassOf ?type .
      filter ( ?type2 != ?type )
   }
}
\end{verbatim}}

This operates by first finding all of \verb|?x|'s types and then filtering those that have a distinct sub-type.  This is correct and \ac{sparql}-compliant, but the negation is expensive.  Alternately, in \ac{pmnt} we can write this:

{\small\begin{verbatim}
prefix par: <http://parliament.semwebcentral.org/parliament#>
select distinct ?x ?type where {
   ?x par:directType ?type .
}
\end{verbatim}}

This is no longer standards-compliant, and it won't necessarily produce exactly the same results.  However, it is significantly less verbose and, in many cases, much faster.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Reification}
\label{section-reification}

\emph{[Yet to be written]}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Configuring and Using Indexes}
\label{section-indexes}

\emph{[Yet to be written]}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\ac{pmnt} in Other Servlet Containers}
\label{section-parliament-with-jena-and-tomcat}

The most common way to deploy \ac{pmnt} uses the Jetty servlet container.  This scenario is discussed above in Section~\ref{section-std-server-deploy}.  However, the \ac{pmnt} distribution contains a war file that can be deployed in any servlet container.  This section discusses how to deploy \ac{pmnt} in other servlet containers, such as Apache Tomcat.

\begin{enumerate}
	\item First acquire and install Apache Tomcat\urlcite{http://tomcat.apache.org/} according to its own installation instructions.  This will result in a directory containing your Tomcat installation, which, in keeping with the customary nomenclature of Tomcat, we will call \path|CATALINA_HOME| here.

	\item Create a directory for the native \ac{pmnt} binaries.  This can reside anywhere on your machine, but just to be concrete we will call this directory \path|CATALINA_HOME/bin/parliament|.

	\item Copy the native binaries into this directory from the \path|bin| directory of the \ac{pmnt} binary distribution.

	\item On Windows only, install the run-time libraries by running the installer in the \path|RedistributablePackages| subdirectory of your \ac{pmnt} distribution.

	\item Once you have chosen your build directory, copy all of the files from it into the \path|CATALINA_HOME/bin/parliament| directory.

	\item In your favorite text editor, open the file
{\small\begin{quote}
\path|CATALINA_HOME/bin/parliament/ParliamentKbConfig.txt|
\end{quote}}
	and change the following line:
\begin{quote}
\texttt{kbDirectoryPath = kb-data}
\end{quote}
	to point to a directory suitable for storing your knowledge base.  In an operational deployment of \ac{pmnt}, this is often set to a large drive dedicated to the storage of the knowledge base, such as a \ac{raid}, \ac{nas}, or \ac{san}.  For testing purposes, the default is fine.  This will store the knowledge base in \path|CATALINA_HOME/bin/kb-data|.

	\item If you have not already done so while installing Tomcat, create a file called \path|setenv.sh| in \path|CATALINA_HOME/bin| and within it set the environment variable \path|CATALINA_OPTS| like so:
{\footnotesize\begin{verbatim}
MIN_MEM=128m
MAX_MEM=512m
PMNT_BIN="$CATALINA_HOME/bin/parliament"
export CATALINA_OPTS=-Djava.library.path=$PMNT_BIN
export CATALINA_OPTS="$CATALINA_OPTS -Xms$MIN_MEM -Xmx$MAX_MEM"
export PARLIAMENT_KB_CONFIG_PATH=$PMNT_BIN/ParliamentKbConfig.txt
export PARLIAMENT_LOG_CONFIG_PATH=$PMNT_BIN/ParliamentLogConfig.txt
export LD_LIBRARY_PATH=$PMNT_BIN
\end{verbatim}}
	On Windows, the file name should be \path|setenv.bat| and its content should look like this:
{\footnotesize\begin{verbatim}
set MIN_MEM=128m
set MAX_MEM=512m
set PMNT_BIN=%CATALINA_HOME%\bin\parliament
set CATALINA_OPTS=-Xms%MIN_MEM% -Xmx%MAX_MEM%
set PARLIAMENT_KB_CONFIG_PATH=%PMNT_BIN%\ParliamentKbConfig.txt
set PARLIAMENT_LOG_CONFIG_PATH=%PMNT_BIN%\ParliamentLogConfig.txt
set PATH=%PMNT_BIN%;%PATH%
\end{verbatim}}
	Note that you can control the amount of memory set aside for the Java virtual machine by changing \verb|MIN_MEM| and \verb|MAX_MEM| in the scripts above.  While it is important to allow the \ac{jvm} sufficient memory, it is also important to realize that \ac{pmnt} is native code, and therefore does not use the Java heap.  Java programmers are often inclined to set \verb|MAX_MEM| close to the total memory of the machine, but this will starve \ac{pmnt} of the memory it needs to achieve good performance.  The default values given above, 128 MB and 512 MB, are reasonable values for machines with 4 to 8 GB of total memory.

	\item Copy \path|parliament.war| from the \ac{pmnt} distribution into Tomcat's appbase directory, which defaults to \path|CATALINA_HOME/webapps|.

	\item Start Tomcat according to its documentation.  For instructions on using your \ac{pmnt} server, see Section~\ref{section-std-server-usage}.

	\item If you redeploy \ac{pmnt} into a running Tomcat instance, the server will need to be restarted.

	\item\emph{Please note:}  When you want to shut down the \ac{kb}, it is important to shut it down gracefully.  Otherwise, the \ac{pmnt} files may not be flushed to disk before they are closed, and they may be badly corrupted.  If you run Tomcat as a Windows service or UNIX Daemon, this is generally not a problem, because the operating system sends a shut-down message at the appropriate time.  If, however, you run Tomcat explicitly via its startup script, you will need to shut it down yourself with Tomcat's stop script.
\end{enumerate}

\subsubsection{Glassfish Notes}
When deploying \ac{pmnt} to Glassfish, note the following:
\begin{itemize}
	\item Glassfish sets it's own \verb|java.library.path| property.  The \ac{pmnt} libraries must either be copied into \path|«Glassfish install dir»/lib| or you must alter the Glassfish configuration such that the libraries are available on \verb|java.library.path|.

	\item By default, \ac{pmnt} stores it's data files in the \path|kb-data| subdirectory of the current working directory.  In the case of Glassfish, this will be \path|«Glassfish install dir»/domains/domain1/config/kb-data|.  To change this, edit \path|ParliamentKbConfig.txt| to change the setting \verb|kbDirectoryPath| to the location (absolute path) where your data files reside.

	\item If \ac{pmnt} is redeployed into a running instance of Glassfish, the server will need to be restarted.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Using \ac{pmnt} In-Process}
\label{section-parliament-in-process}

Jena is a popular toolkit for manipulating \ac{rdf} data in Java programs.  The central concept in the Jena class library is the Model interface.  An object of type Model represents a graph of \ac{rdf} data, and features many methods for manipulating that data.  With just a few lines of code, you can create a Jena Model that is backed by an instance of \ac{pmnt}, as demonstrated by Figure~\ref{figure-creating-jena-model}.
	\begin{figure}[htbp]
		\footnotesize
		\centering
		\begin{verbatim}
import java.io.File;
import com.bbn.parliament.jena.graph.KbGraph;
import com.bbn.parliament.jena.graph.KbGraphFactory;
import com.bbn.parliament.jni.Config;
import com.hp.hpl.jena.rdf.model.Model;
import com.hp.hpl.jena.rdf.model.ModelFactory;

private Model createParliamentModel()
{
  KbGraph baseGraph = KbGraphFactory.createDefaultGraph();
  return ModelFactory.createModelForGraph(baseGraph);
}
		\end{verbatim}
		\caption{Creating a Jena Model backed by \ac{pmnt}}
		\label{figure-creating-jena-model}
	\end{figure}
The \verb|createParliamentModel| method returns a Jena model backed by a \ac{pmnt} instance.  With this model, you can do any of the things you normally do with a Jena model, such as call \verb|read| on it to load a file into it, or query it.

The \verb|useParliamentModel| method shown in Figure~\ref{figure-using-jena-model} demonstrates how to call \verb|createParliamentModel|.  The important thing to note here is the try-finally construct.  This guarantees that the model is closed properly, even if an exception is thrown.  Closing the model is crucial, because if you don't, the \ac{pmnt} files will not be flushed to disk before they are closed, and they will almost certainly be badly corrupted.

	\begin{figure}[htbp]
		\footnotesize
		\centering
		\begin{verbatim}
import com.hp.hpl.jena.rdf.model.Model;

void useParliamentModel()
{
  Model kbModel = createParliamentModel();
  try
  {
    // Use the model according to the Jena documentation.
    // For instance, to issue a SPARQL query:
    QueryExecution exec = QueryExecutionFactory.create(
      sparqlQueryString, kbModel);
    for (ResultSet rs = exec.execSelect(); rs.hasNext(); rs.next())
    {
      // Do something useful with the result set here
    }
  }
  finally
  {
    if (kbModel != null && !kbModel.isClosed())
    {
      kbModel.close();
      kbModel = null;
    }
  }
}
		\end{verbatim}
		\caption{Using a Jena Model backed by \ac{pmnt}}
		\label{figure-using-jena-model}
	\end{figure}

Naturally, there is some setup required to make this work:
\begin{enumerate}
	\item You will need \path|JenaParliament.jar| and \path|Parliament.jar| from your binary distribution, along with the Jena jar files, which you can download from the Jena web site\urlcite{https://jena.apache.org/}.  Place all of these jar files in a convenient location and ensure that they are added to your class path.  (If you are using Eclipse, add them to the build path.)

	\item Copy the following files from the \path|bin| directory of the \ac{pmnt} distribution to a convenient location, such as the directory used for the jar files above:
	\begin{itemize}[noitemsep]
		\item All of the \acp{dll}\footnote{Or ``shared libraries'' on UNIX-like systems.  For brevity, we will just use ``\acp{dll}.''}.
		\item \path|ParliamentAdmin| (\path|ParliamentAdmin.exe| on Windows)
		\item \path|ParliamentKbConfig.txt|
		\item \path|ParliamentLogConfig.txt|
	\end{itemize}

	\item Ensure that the \ac{jvm} can find the \acp{dll} or shared libraries at run-time.  For Mac OS X, add their directory to the Java system property \verb|java.library.path|.  On Windows, add the directory to the \verb|Path| environment variable.  On Linux, it's \verb|LD_LIBRARY_PATH|.  Many flavors of UNIX also use \verb|LD_LIBRARY_PATH|, though some differ.  Consult your operating system documentation to find the correct variable name.

	\item On Windows only, install the run-time libraries by running the installer in the \path|RedistributablePackages| subdirectory of your \ac{pmnt} distribution.

	\item Customize the configuration \path|ParliamentKbConfig.txt| as desired.  In particular, the \texttt{kbDirectoryPath} setting defaults to \path|./kb-data|.  To place your \ac{pmnt} \ac{kb} files in a different location, change this setting to the directory of your choice.  This is especially useful for placing the \ac{kb} files on a drive array or for maintaining several \acp{kb} and switching between them.

	\item Set the environment variables \verb|PARLIAMENT_KB_CONFIG_PATH| and its companion \verb|PARLIAMENT_LOG_CONFIG_PATH| to the paths of the corresponding configuration files.  On Windows, if these are not set the files will be loaded from the same directory as the \ac{pmnt} \ac{dll}.  On other platforms these environment variables are required.
\end{enumerate}

If you do not wish to use the \ac{pmnt} configuration file to configure your application, you can replace the first line of the method in Figure~\ref{figure-creating-jena-model}, \verb|createParliamentModel|, with a line that creates a Config instance using the default constructor and then set the Config fields yourself.  This may be useful for centralizing your application's configuration in a single file.

If \verb|createParliamentModel| throws an \verb|UnsatisfiedLinkError| exception, see Section~\ref{section-troubleshooting} for possible resolutions.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The ParliamentAdmin Utility}
\label{section-parliamentadmin-utility}

\emph{[Yet to be written]}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Troubleshooting}
\label{section-troubleshooting}

Because \ac{pmnt} is most often used within a Java environment, the most common problem is the dreaded ``Unsatisfied Link Error''.  This error is generated by the \ac{jvm} when the Java code requests the loading of a \ac{dll}, but the \ac{jvm} is unable to load that \ac{dll}.  There are quite a few reasons why you may encounter an unsatisfied link error, and unfortunately, the \ac{jvm} is not very good about generating an illuminating error message.  So, should you encounter this problem, here are some things to keep in mind:
\begin{itemize}
	\item Double-check that you have followed all the deployment instructions correctly for your chosen mode of deployment.

	\item Make sure that your system is up-to-date with respect to patches.  For Windows, this means a visit to the Windows Update web site\urlcite{http://windowsupdate.microsoft.com/}.  Most other operating systems have a similar facility.

	\item Be sure that a 64-bit build of \ac{pmnt} is loaded by a 64-bit version of Java, and that a 32-bit build of \ac{pmnt} is loaded by a 32-bit version of Java.  On Macintosh, this is not a problem, because \ac{pmnt} is built as a universal binary.

	\item When the \ac{jvm} loads the \ac{pmnt} \ac{dll}, \ac{pmnt} itself loads several other \acp{dll}.  Even if the \ac{jvm} is able to load \ac{pmnt}, an unsatisfied link error will result if \ac{pmnt} cannot load one of its subsidiary \acp{dll}.  Furthermore, the error message accompanying the unsatisfied link error usually does not indicate which \ac{dll} caused the load failure.  The subsidiary \acp{dll} fall into the following three categories:
	\begin{itemize}
		\item The Berkeley DB and Boost \acp{dll}:  In the deployment procedures detailed in this document, these \acp{dll} should reside in the same location as \ac{pmnt} itself.
		\item The C and C++ run-time libraries:  On Unix-like systems these should be available automatically.  On Windows you may need to install the Visual Studio run-time libraries.  You can find installers for these in the \path|RedistributablePackages| subdirectory of your binary distribution of \ac{pmnt}.
		\item Various operating system \acp{dll}:  These are rarely a problem, because the OS needs to be able to find these to function.
	\end{itemize}

	\item The Java system property \verb|java.library.path| is a list of paths that Java searches when loading native libraries.  This suggests that all of the operating system-specific rules for locating \acp{dll} can be circumvented by providing a suitable definition for this system property.  Unfortunately, when Java loads a library that itself loads other libraries (as \ac{pmnt} does), Java can consult \verb|java.library.path| only when loading the top-level library, because the loading process for its dependents is managed entirely within the operating system.  Thus, this property does not solve the problem for \ac{pmnt}.

	\item Running \path|ParliamentAdmin| helps to diagnose unsatisfied link errors, because this tool also loads the \ac{pmnt} \ac{dll}, but it does so without involving Java (because \path|ParliamentAdmin| is written in C++).  This technique can be used to isolate the error to either the operating system level (when \path|ParliamentAdmin| fails to load the \ac{dll}) or to the Java level (when \path|ParliamentAdmin| succeeds).  Even the simple command ``\path|ParliamentAdmin -v|'' to get the version requires loading the \ac{pmnt} \ac{dll}, so this is an easy test.

	\item Multiple Java installations can confuse the \ac{dll} loading process.  The scripts \path|StartParliament.sh| and \path|StartParliament.bat| find Java by simply invoking the command \path|java| and relying on the operating system to locate the installation.  In these cases, the \verb|JAVA_HOME| environment variable is not used, unless the operating system uses it.  On Windows, the process by which the \path|java| command finds and loads the \ac{jvm} is quite complex.  The following web page sheds some light on how you can manage this process:
\begin{quote}\small
	\url{http://mindprod.com/jgloss/javaexe.html#MULTIPLES}
\end{quote}
In the case of the \path|InstallParliamentService| script, the situation is quite different.  The \path|java| command is not used at all, and instead the service executable directly loads the \path|jvm.dll| library.  This is located by using the \verb|JAVA_HOME| environment variable at the time the service is installed.  (This means that if you upgrade your Java installation after installing the service, you will have to uninstall and reinstall the service in order for it to find the \path|jvm.dll| library.)

	\item The process by which Windows searches for \acp{dll} is somewhat complex, so understanding it can often help pinpoint the problem.  The search process is as follows:

	\begin{itemize}
		\item The Windows system directory
		\item The Windows directory
		\item The directory where the executable module for the current process is located
		\item The current directory
		\item The directories listed in the \verb|PATH| environment variable
	\end{itemize}

Note that placing \acp{dll} in the Windows or Windows system directories is strongly discouraged.

Both the graphical tool Dependency Walker\urlcite{http://dependencywalker.com/} and the command-line tool \path|dumpbin| (part of the Visual Studio installation) show from where Windows is trying to load subsidiary \acp{dll}.  (Note that some operating system \acp{dll} themselves load many other libraries, some by magic.  This can confuse Dependency Walker, causing it to report missing \acp{dll}.  These error messages are, however, red herrings and should be ignored.)

	\item On Mac OS X, the \ac{jvm} finds the \ac{pmnt} shared library by consulting the Java system property \verb|java.library.path|, and the operating system looks for its dependencies in the same directory.  The command ``\path|otool -L|'' will show from where the operating system is trying to load subsidiary shared libraries.

	\item Other UNIX-like systems find shared libraries by searching the directories in the library search path environment variable.  The name of this variable differs by system:  On Linux and several others it is \verb|LD_LIBRARY_PATH|, though some differ.  On most UNIX-like systems the command \path|ldd| will show from where the operating system is trying to load subsidiary shared libraries.

	\item A debug build of \ac{pmnt} will not work on Windows unless the corresponding version of Visual Studio is installed.  This is because the debug versions of the C and C++ run-time libraries are included only with Visual Studio.

	\item More rarely, unsatisfied link errors can result from a bad build of \ac{pmnt} that causes the symbols exported from the \ac{dll} to be named incorrectly.  If this happen, the \ac{jvm} will succeed in loading the \ac{dll}, but fail to find the entry points it needs.  This results in an unsatisfied link error that is indistinguishable from the cases where the \ac{jvm} cannot load the \ac{dll} at all.  This condition is more likely to occur on Windows, and usually has something to do with the symbol \verb|BUILDING_KBCORE| not being defined on the compiler command line.
\end{itemize}
